Release 10.1A: OpenEdge Development:
Progress 4GL Reference

DEFINE BUFFER statement

Progress provides you with one buffer for each table that you use in a procedure. Progress uses that buffer to store one record at a time from the table as the records are needed during the procedure. If you need more than one record at a time from a table, you can use the DEFINE BUFFER statement to define additional buffers for that table. If you need to share buffers among procedures, use the DEFINE SHARED BUFFER statement.

Syntax

DEFINE [ [ NEW ] SHARED ]        [ PRIVATE | PROTECTED ] BUFFER buffer-name        FOR [ TEMP-TABLE ] table-name [ PRESELECT ] [ LABEL label-name ]        [ NAMESPACE-URI namespace ] [ NAMESPACE-PREFIX prefix ]

NEW SHARED BUFFER buffer-name

Defines and identifies a buffer that can be used by other procedures. When the procedure using this statement ends, the buffer is no longer available.

SHARED BUFFER buffer-name

Defines and identifies a buffer that was created in another procedure with the DEFINE NEW SHARED BUFFER statement.

[ PRIVATE | PROTECTED ] BUFFER buffer-name

Defines and identifies a buffer as a data member for a class, and optionally specifies an access mode for that data member. Do not specify an access mode when defining a buffer for a method within a class.

PRIVATE data members can be accessed only by the defining class. PROTECTED data members can be accessed by the defining class and any of its inheriting classes. The default access mode is PRIVATE.

Note: These options are applicable only when defining a data member for a class in a class definition (.cls) file.

BUFFER buffer-name

Identifies the name of the buffer you want to define to hold records from table-name. You can define the buffer in a procedure or a method within a class.

FOR [ TEMP-TABLE ] table-name

Identifies the name of the table for which you are defining an additional buffer. This can also be the built-in buffer name, proc-text-buffer, to define a buffer that returns table rows from a stored procedure.

To define a buffer for a table defined for multiple databases, you might have to qualify the table name with the database name. See the Record phrase reference entry for more information.

Use the TEMP-TABLE option to define a buffer for a temporary table when the temporary table has the same name as a database table. Otherwise, Progress associates the buffer with the database table by default.

PRESELECT

If you use the PRESELECT option with a DO or REPEAT block, Progress creates an internal list of the records selected. The PRESELECT option tells Progress to apply that internal list to the buffer you define. You can also use the PRESELECT option in the DEFINE SHARED BUFFER statement.

LABEL label-name

Specifies a label for the buffer. This label is used in error messages in place of the buffer name.

NAMESPACE-URI namespace

An optional CHARACTER constant that specifies the URI for the namespace of the buffer object.

NAMESPACE-PREFIX prefix

An optional CHARACTER constant that specifies the namespace prefix associated with the NAMESPACE-URI.

Examples

This procedure allows the user to create a new customer record. Initially, the City, State, and Country fields are not shown. After the user enters a Postal-Code value, the procedure searches for an existing customer with the same postal code. If such a customer is found, the City, State, and Country values from that record are displayed in the fields for the new record. The user can then update those fields.

r-defb.p

DEFINE BUFFER other-cust FOR Customer. FORM Customer WITH FRAME cre-cust. ON LEAVE OF Customer.Postal-Code DO: FIND FIRST other-cust WHERE other-cust.Postal-Code = Customer.Postal-Code:SCREEN-VALUE AND other-cust.Cust-num <> Customer.Cust-num NO-ERROR. IF AVAILABLE(other-cust) THEN DISPLAY other-cust.City @ Customer.City other-cust.State @ Customer.State other-cust.Country @ Customer.Country WITH FRAME cre-cust. ENABLE Customer.City Customer.State Customer.Country WITH FRAME cre-cust. END. CREATE Customer. UPDATE Customer EXCEPT Customer.City Customer.State Customer.Country WITH FRAME cre-cust.

The following gather a group of records so that the user can enter any table name and any set of record selection criteria and then look at the records in the table that meet those criteria.

r-defb2.p

DEFINE VARIABLE fname AS CHARACTER FORMAT "x(12)" LABEL "Table name". DEFINE VARIABLE conditions AS CHARACTER FORMAT "x(60)" LABEL "Conditions". REPEAT: /* Get the name of a table and, optionally, some record selection criteria */ UPDATE fname COLON 12 conditions COLON 12 WITH SIDE-LABELS 1 DOWN. HIDE ALL. IF conditions <> "" /* Pass the table name and the record selection criteria as parameters */ THEN RUN r-defb3.p fname "WHERE" conditions. ELSE RUN r-defb3.p fname. END.

The r-defb2.p procedure gets the name of a table (such as customer) and a condition (such as credit-limit > 4000) and passes them as arguments to the r-defb3.p procedure.

r-defb3.p

DEFINE NEW SHARED BUFFER rec FOR {1} PRESELECT. DEFINE VARIABLE flist AS CHARACTER EXTENT 12. DEFINE VARIABLE I AS INTEGER. /* Look in _File the table named in the filename variable */ FIND _File "{1}". /* Store the table’s field names in the first array */ FOR EACH _Field OF _File USE-INDEX _Field-posit: IF i >= 12 THEN LEAVE. i = i + 1. flist[i] = _Field._Field-name. END. /* Preselect records */ DO PRESELECT EACH rec {2} {3} {4} {5} {6} {7} {8} {9} {10} {11} {12}: /* Pass the filenames and all field names to r-defb4.p */ RUN r-defb4.p "{1}" flist[1] flist[2] flist[3] flist[4] flist[5] flist[6] flist[7] flist[8] flist[9] flist[10] flist[11] flist[12]. END.

The r-defb3.p procedure:

Lets you view the OpenEdge Data Dictionary. The _File table contains a record for each of your database tables.
Lets you look up a record for a customer table. For example, the user supplies Customer as a table name; the FIND statement in the r-defb3.p procedure translates to FIND _File Customer. The FIND statement finds, in _File, the record for the customer table.
Lets you view the _Field table in the OpenEdge Data Dictionary. The _Field table contains a single record for each of your database fields. The FOR EACH statement reads the name of each of those fields into the first array variable. If the table name is Customer, the first array variable contains the names of each of the fields in the Customer table.
Lets you select records. For example, the user supplies the condition credit-limit > 4000 in the table name. The DO PRESELECT EACH rec statement translates to DO PRESELECT EACH rec WHERE max-credit > 4000. Progress goes through the customer table and selects the records that meet the criteria. It creates a temporary table containing a pointer to each of those records. This list of preselected records is associated with the rec buffer.
Runs r-defb4.p, passing the table name (Customer) and the names of all of the fields in that table.

The r-defb4.p procedure has access to the rec buffer (and through it to the set of preselected records). This connection is made by using PRESELECT on the DEFINE SHARED BUFFER statement. The r-defb4.p procedure displays those records.

r-defb4.p

DEFINE SHARED BUFFER rec FOR {1} PRESELECT. REPEAT: FIND NEXT rec. display {2} {3} {4} {5} {6} {7} {8} {9} {10} {11} {12} {13} WITH 1 COLUMN 1 DOWN. END.

Because r-defb3.p and r-defb4.p use run-time argument passing, they cannot be precompiled. Having separate versions of r-defb4.p for each table and running the appropriate one in r-defb3.p, should improve response time. This approach is worthwhile if there are many lines of code in r-defb4.p a procedure.

If you define a NEW SHARED BUFFER in a procedure, then call a subprocedure that puts a record into that buffer, and display the buffer in the main procedure, Progress displays this message:

Missing FOR, FIND or CREATE for customer.

This message is displayed when the FIND statement is not in the main procedure:

/* Main procedure */ DEFINE NEW SHARED BUFFER x FOR customer. RUN proc2.p. DISPLAY x.

/* proc2.p */ DEFINE SHARED BUFFER x FOR customer. FIND FIRST x.

To avoid this, explicitly scope the customer record to the main procedure block. For example:

/* Main procedure */ DEFINE NEW SHARED BUFFER x FOR customer. RUN proc2.p. DO FOR x: DISPLAY x. END.

Notes

You cannot define a SHARED or NEW SHARED buffer in a class definition (.cls) file. If you do, Progress generates a compilation error.
Every statement that uses a table name to refer to the default buffer can also use the name of a defined alternate buffer.
All data definitions and field names are associated with a table, not a buffer. Data definitions and field names remain the same no matter what buffer you use.
If two buffers contain the same record, a change to one of the buffers is automatically reflected in the other buffer.
You can pass a buffer as a parameter to a procedure.
A SHARED buffer remains in scope for an instance of a persistent procedure until the instance is deleted. This is true even if the original procedure that defined the buffer as NEW SHARED goes out of scope while the procedure instance remains persistent.

If a trigger or internal procedure of a persistent procedure executes an external subprocedure that defines a SHARED buffer, Progress includes the persistent procedure in the resolution of the corresponding NEW SHARED buffer as though the procedure were on the procedure call stack.

If you define a temporary table with the same name as a database table and then you define a buffer for that table name, the buffer will be associated with the database table, not with the temporary table, by default. Use the TEMP-TABLE option to define a buffer for a temporary table when the temporary table has the same name as a database table.
For more information on using the built-in buffer name proc-text-buffer, see the OpenEdge DataServer Guides, OpenEdge Data Management: DataServer for Microsoft SQL Server , OpenEdge Data Management: DataServer for ODBC , and OpenEdge Data Management: DataServer for ORACLE .

See also

DEFINE PARAMETER statement, RUN statement, RUN STORED-PROCEDURE statement